NSBJPGview V1.0
2004-01-20

David Thacker
Thacker Network Technologies Inc.
http://www.PalmDataPro.com


What is it?
-----------

NSBJPGview is an NSBasic/Palm extension that enables you to view JPG
images in your NSB application.  JPG images files stored in the Palm's
main memory (RAM) and on VFS expansion cards are supported.

JPG images are scaled to the dimensions and location on the form that
you specify.  High density displays are supported.

NSBJPGview requires no other third party viewer application (such as
SplashPhoto), and displays the image directly on your NSB application's
form.  NSBJPGview currently displays images on Palm devices with ARM
processors (all devices running PalmOS5 and higher) only, and does not
display an image on devices with Motorola 68K processors (all PalmOS 4.x
and older devices).


How To Use NSBJPGview
---------------------

Use the JPG_IsARM function when your app starts, to test whether the
current device has an ARM processor.  If it does, then you should set
the screen bit depth to 16 bit (most color devices default to 8 bit)
using the JPG_SetScreenDepth16 function, which is required for proper
JPG image display. If the device does not have an ARM processor, you may
wish to display an informative error message, or you may just want to
hide all of the functions in your app that would have used NSBJPGview to
display images.  Attempting to display an image on a 68K device will not
generate any errors: it just won't display an image.

Make sure you provide proper case-sensitive filenames of the image files
that you wish to display.  When using images from a VFS card, be sure to
use the correct file path.  It is possible to have JPG files stored in
different paths, for example.  A common standard on VFS cards is the
/DCIM/ folder, which is often used by digital cameras.

A full-featured sample application is provided that demonstrates how to
implement the NSBJPGview functions.  Review each of the button scripts,
app startup script, and the global subs code module in the sample app as
a guide.  A sample JPG image for internal memory is also provided as
Lake_jpg.PDB.  When you install this to PalmSim or a real Palm device,
it will have the name Lake.jpg.  (NOTE: This file cannot be used as is
on a VFS card, as it will show up as a PDB file rather than a JPG file.)

You do not need to install any INF files into the NSBasic IDE like you
do with shared libraries.  NSBJPGview is an "applaunch" type extension,
and everything is handled within your app code without needing an INF
file.


Method Reference
----------------

The following global extension methods are provided:

1. JPG_About
    - Display an About box for the NSBJPGview extension, listing the
    version and serial number.

    USAGE: JPG_About()


2. JPG_JPG_ShowJPG
    - Show JPG image at desired location and size.  The image will be
    scaled to fit.

    USAGE: result = JPG_ShowJPG( filename as String, card as Integer, x as integer, y as integer, w as integer, h as integer )

    Use this function to display a JPG photo at the desired location and
    at the specified width and height.  This function will scale the
    image, keeping the original aspect ratio intact (no stretching),
    into the size you specify.  Any valid JPG file can be displayed,
    except those that use progressive encoding.

    The name parameter must be the case sensitive filename of the JPG
    file.  For JPG files in internal memory it is case sensitive, but
    for file on an expansion card it is not case sensitive.  For files
    on an expansion card, the name must be the full path and name of the
    image (eg. "/DCIM/myphoto.jpg"), whereas for internal files it would
    just be the filename (eg. "myphoto.jpg").

    The card value specifies whether the file is in internal memory
    (card = 0) or on the expansion card (card = 1).

    The x and y values specify the upper left x and y coordinates
    on the screen where you want the image to be displayed.  These are
    standard density (160x160) screen coordinates.

    The w and h values specify the width and height you wish to
    display the image at, and the image will be proportionally scaled to
    fit this width and height if needed.  These are standard density
    (160x160) values, though the image is displayed in high density mode.

    This function returns a standard PalmOS error code if there is an
    error, or 0 if there is no error.  Refer to the error code listing
    further below in this readme file for error code details.


3. JPG_ExistsJPG
    - Test if JPG file exists.

    USAGE: result = JPG_ExistsJPG( filename as String, card as Integer )

    Use this function to test whether a JPG file exists before
    attempting to display it.

    The name parameter must be the case sensitive filename of the JPG
    file.  For JPG files in internal memory it is case sensitive, but
    for file on an expansion card it is not case sensitive.  For files
    on an expansion card, the name must be the full path and name of the
    image (eg. "/DCIM/myphoto.jpg"), whereas for internal files it would
    just be the filename (eg. "myphoto.jpg").

    The card value specifies whether the file is in internal memory
    (card = 0) or on the expansion card (card = 1).

    This function returns a 1 (true) if the file exists, or a 0 (false)
    if it is not found.


4. JPG_HasVFS
    - Find out if this Palm device has VFS support.

    USAGE: result = JPG_HasVFS()

    Use this function to test whether the device supports VFS cards or
    not.

    Returns 0 (false) or 1 (true).


5. JPG_IsARM
    - Find out if this Palm device has an ARM processor.

    USAGE: result = JPG_HasVFS()

    Use this function to test whether the device has an ARM processor
    (and is therefore capable of diplsaying JPG images) or not.  If the
    device does not have an ARM processor, then it will not be able to
    display JPG images using NSBJPGview.

    Returns 0 (false) or 1 (true).


6. JPG_JPG_SetScreenDepth16
    - Set screen depth to 16 bits.

    USAGE: result = JPG_SetScreenDepth16()

    Always returns 1 (true).

    Use this function to set the screen bit depth to 16 bits, which is
    required to display JPG images properly.



Getting JPGs into the Palm Device
---------------------------------

JPGs in the Palm's internal memory are stored as a special type of PDB
called streamed databases.  You can use a utility called PAR to take
desktop JPG files and create JPG streamed database for installing on the
Palm.  PAR can be found at
http://www.djw.org/product/palm/par/index.html

JPG to PDB
----------
The PAR commandline parameters for taking any PC JPG file and converting it
to a "JPG PDB" streamed file for use with NSBJPGview and other viewers are:

                  (A)          (B)      (C)  (D)  (E)
par c -a "stream" name.JPG.pdb name.JPG CRID Foto name.jpg

(A) - name of the PDB file to create
(B) - Palm internal name of the streamed file (the filename you would use on the Palm)
(C) - creatorID of the PDB file to be created
(D) - type of the PDB file to be created
(E) - pathname of the JPG file on the PC to convert

Hotsync that PDB file to the Palm device, where it will show up in
internal memory as "name.JPG" without the .PDB extension.


JPGs on an expansion card are standard PC format files, with
no conversion necessary.  By convention it is recommended that you place
JPG file in the /DCIM/ folder on the card.  The easiest way to manage
this is to use a USB card reader attached to your PC.


COPYRIGHT AND DISTRIBUTION
--------------------------

Please remember that this software is a commercial product and is
protected by strict copyright laws. Any unauthorized reproduction or
distribution is strictly forbidden.

Created by: David Thacker

Copyright (C) 2004 Thacker Network Technologies Inc.

Thacker Network Technologies Inc.
5338 - 51 Ave.
Lacombe, AB  T4L 1N5  CANADA
Tel: +1-403-782-5432
Fax: +1-403-782-1794
Email: Sales@PalmDataPro.com
Http://www.PalmDataPro.com
